---
title: Installation
---

Install the package from PyPI:

```bash
pip install cua-mcp-server
```

This will install:

- The MCP server
- CUA agent and computer dependencies
- An executable `cua-mcp-server` script in your PATH

## Easy Setup Script

If you want to simplify installation, you can use this one-liner to download and run the installation script:

```bash
curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/python/mcp-server/scripts/install_mcp_server.sh | bash
```

This script will:

- Create the ~/.cua directory if it doesn't exist
- Generate a startup script at ~/.cua/start_mcp_server.sh
- Make the script executable
- The startup script automatically manages Python virtual environments and installs/updates the cua-mcp-server package

You can then use the script in your MCP configuration like this:

```json
{
  "mcpServers": {
    "cua-agent": {
      "command": "/bin/bash",
      "args": ["~/.cua/start_mcp_server.sh"],
      "env": {
        "CUA_MODEL_NAME": "anthropic/claude-sonnet-4-20250514",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key-here"
      }
    }
  }
}
```

**Important**: You must include your Anthropic API key for the MCP server to work properly.

## Development Setup

If you're working with the CUA source code directly (like in the CUA repository), you can use the development script instead:

```json
{
  "mcpServers": {
    "cua-agent": {
      "command": "/usr/bin/env",
      "args": [
        "bash",
        "-lc",
        "export CUA_MODEL_NAME='anthropic/claude-sonnet-4-20250514'; export ANTHROPIC_API_KEY='your-anthropic-api-key-here'; /path/to/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"
      ]
    }
  }
}
```

**For host computer control** (development setup):

1. **Install Computer Server Dependencies**:

   ```bash
   python3 -m pip install uvicorn fastapi
   python3 -m pip install -e libs/python/computer-server --break-system-packages
   ```

2. **Start the Computer Server**:

   ```bash
   cd /path/to/cua
   python -m computer_server --log-level debug
   ```

   This will start the computer server on `http://localhost:8000` that controls your actual desktop.

3. **Configure Claude Desktop**:
   ```json
   {
     "mcpServers": {
       "cua-agent": {
         "command": "/usr/bin/env",
         "args": [
           "bash",
           "-lc",
           "export CUA_MODEL_NAME='anthropic/claude-sonnet-4-20250514'; export ANTHROPIC_API_KEY='your-anthropic-api-key-here'; export CUA_USE_HOST_COMPUTER_SERVER='true'; export CUA_MAX_IMAGES='1'; /path/to/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"
         ]
       }
     }
   }
   ```

**Note**: Replace `/path/to/cua` with the absolute path to your CUA repository directory.

**⚠️ Important**: When using host computer control (`CUA_USE_HOST_COMPUTER_SERVER='true'`), the AI will have direct access to your desktop and can perform actions like opening applications, clicking, typing, and taking screenshots. Make sure you're comfortable with this level of access.

### Troubleshooting

**Common Issues:**

1. **"Claude's response was interrupted"** - This usually means:
   - Missing API key: Add `ANTHROPIC_API_KEY` to your environment variables
   - Invalid model name: Use a valid model like `anthropic/claude-sonnet-4-20250514`
   - Check logs for specific error messages

2. **"Missing Anthropic API Key"** - Add your API key to the configuration:

   ```json
   "env": {
     "ANTHROPIC_API_KEY": "your-api-key-here"
   }
   ```

3. **"model not found"** - Use a valid model name:
   - ✅ `anthropic/claude-sonnet-4-20250514`
   - ✅ `anthropic/claude-3-5-sonnet-20240620`
   - ❌ `anthropic/claude-3-5-sonnet-20241022` (doesn't exist)

4. **Script not found** - If you get a `/bin/bash: ~/cua/libs/python/mcp-server/scripts/start_mcp_server.sh: No such file or directory` error, try changing the path to the script to be absolute instead of relative.

5. **Host Computer Control Issues** - If using `CUA_USE_HOST_COMPUTER_SERVER='true'`:
   - **Computer Server not running**: Make sure you've started the computer server with `python -m computer_server --log-level debug`
   - **Port 8000 in use**: Check if another process is using port 8000 with `lsof -i :8000`
   - **Missing dependencies**: Install `uvicorn` and `fastapi` with `python3 -m pip install uvicorn fastapi`
   - **Image size errors**: Use `CUA_MAX_IMAGES='1'` to reduce image context size

**Viewing Logs:**

```bash
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```
